home *** CD-ROM | disk | FTP | other *** search
/ PC World 2006 July & August / PCWorld_2006-07-08_cd.bin / komunikace / apache / apache_2[1].2.2-win32-x86-no_ssl.msi / Data1.cab / _A57BB9F365E1EEB27FBB326C51CA234D < prev    next >
Text File  |  2005-02-04  |  13KB  |  357 lines
  1. /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
  2.  * applicable.
  3.  *
  4.  * Licensed under the Apache License, Version 2.0 (the "License");
  5.  * you may not use this file except in compliance with the License.
  6.  * You may obtain a copy of the License at
  7.  *
  8.  *     http://www.apache.org/licenses/LICENSE-2.0
  9.  *
  10.  * Unless required by applicable law or agreed to in writing, software
  11.  * distributed under the License is distributed on an "AS IS" BASIS,
  12.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13.  * See the License for the specific language governing permissions and
  14.  * limitations under the License.
  15.  */
  16. /**
  17.  * @file apr_xml.h
  18.  * @brief APR-UTIL XML Library
  19.  */
  20. #ifndef APR_XML_H
  21. #define APR_XML_H
  22.  
  23. /**
  24.  * @defgroup APR_Util_XML XML 
  25.  * @ingroup APR_Util
  26.  * @{
  27.  */
  28. #include "apr_pools.h"
  29. #include "apr_tables.h"
  30. #include "apr_file_io.h"
  31.  
  32. #include "apu.h"
  33. #if APR_CHARSET_EBCDIC
  34. #include "apr_xlate.h"
  35. #endif
  36.  
  37. #ifdef __cplusplus
  38. extern "C" {
  39. #endif
  40.  
  41. /**
  42.  * @package Apache XML library
  43.  */
  44.  
  45. /* -------------------------------------------------------------------- */
  46.  
  47. /* ### these will need to move at some point to a more logical spot */
  48.  
  49. /** @see apr_text */
  50. typedef struct apr_text apr_text;
  51.  
  52. /** Structure to keep a linked list of pieces of text */
  53. struct apr_text {
  54.     /** The current piece of text */
  55.     const char *text;
  56.     /** a pointer to the next piece of text */
  57.     struct apr_text *next;
  58. };
  59.  
  60. /** @see apr_text_header */
  61. typedef struct apr_text_header apr_text_header;
  62.  
  63. /** A list of pieces of text */
  64. struct apr_text_header {
  65.     /** The first piece of text in the list */
  66.     apr_text *first;
  67.     /** The last piece of text in the list */
  68.     apr_text *last;
  69. };
  70.  
  71. /**
  72.  * Append a piece of text to the end of a list
  73.  * @param p The pool to allocate out of
  74.  * @param hdr The text header to append to
  75.  * @param text The new text to append
  76.  */
  77. APU_DECLARE(void) apr_text_append(apr_pool_t *p, apr_text_header *hdr,
  78.                                   const char *text);
  79.  
  80.  
  81. /* --------------------------------------------------------------------
  82. **
  83. ** XML PARSING
  84. */
  85.  
  86. /*
  87. ** Qualified namespace values
  88. **
  89. ** APR_XML_NS_DAV_ID
  90. **    We always insert the "DAV:" namespace URI at the head of the
  91. **    namespace array. This means that it will always be at ID==0,
  92. **    making it much easier to test for.
  93. **
  94. ** APR_XML_NS_NONE
  95. **    This special ID is used for two situations:
  96. **
  97. **    1) The namespace prefix begins with "xml" (and we do not know
  98. **       what it means). Namespace prefixes with "xml" (any case) as
  99. **       their first three characters are reserved by the XML Namespaces
  100. **       specification for future use. mod_dav will pass these through
  101. **       unchanged. When this identifier is used, the prefix is LEFT in
  102. **       the element/attribute name. Downstream processing should not
  103. **       prepend another prefix.
  104. **
  105. **    2) The element/attribute does not have a namespace.
  106. **
  107. **       a) No prefix was used, and a default namespace has not been
  108. **          defined.
  109. **       b) No prefix was used, and the default namespace was specified
  110. **          to mean "no namespace". This is done with a namespace
  111. **          declaration of:  xmlns=""
  112. **          (this declaration is typically used to override a previous
  113. **          specification for the default namespace)
  114. **
  115. **       In these cases, we need to record that the elem/attr has no
  116. **       namespace so that we will not attempt to prepend a prefix.
  117. **       All namespaces that are used will have a prefix assigned to
  118. **       them -- mod_dav will never set or use the default namespace
  119. **       when generating XML. This means that "no prefix" will always
  120. **       mean "no namespace".
  121. **
  122. **    In both cases, the XML generation will avoid prepending a prefix.
  123. **    For the first case, this means the original prefix/name will be
  124. **    inserted into the output stream. For the latter case, it means
  125. **    the name will have no prefix, and since we never define a default
  126. **    namespace, this means it will have no namespace.
  127. **
  128. ** Note: currently, mod_dav understands the "xmlns" prefix and the
  129. **     "xml:lang" attribute. These are handled specially (they aren't
  130. **     left within the XML tree), so the APR_XML_NS_NONE value won't ever
  131. **     really apply to these values.
  132. */
  133. #define APR_XML_NS_DAV_ID    0    /**< namespace ID for "DAV:" */
  134. #define APR_XML_NS_NONE        -10    /**< no namespace for this elem/attr */
  135.  
  136. #define APR_XML_NS_ERROR_BASE    -100    /**< used only during processing */
  137. /** Is this namespace an error? */
  138. #define APR_XML_NS_IS_ERROR(e)    ((e) <= APR_XML_NS_ERROR_BASE)
  139.  
  140. /** @see apr_xml_attr */
  141. typedef struct apr_xml_attr apr_xml_attr;
  142. /** @see apr_xml_elem */
  143. typedef struct apr_xml_elem apr_xml_elem;
  144. /** @see apr_xml_doc */
  145. typedef struct apr_xml_doc apr_xml_doc;
  146.  
  147. /** apr_xml_attr: holds a parsed XML attribute */
  148. struct apr_xml_attr {
  149.     /** attribute name */
  150.     const char *name;
  151.     /** index into namespace array */
  152.     int ns;
  153.  
  154.     /** attribute value */
  155.     const char *value;
  156.  
  157.     /** next attribute */
  158.     struct apr_xml_attr *next;
  159. };
  160.  
  161. /** apr_xml_elem: holds a parsed XML element */
  162. struct apr_xml_elem {
  163.     /** element name */
  164.     const char *name;
  165.     /** index into namespace array */
  166.     int ns;
  167.     /** xml:lang for attrs/contents */
  168.     const char *lang;
  169.  
  170.     /** cdata right after start tag */
  171.     apr_text_header first_cdata;
  172.     /** cdata after MY end tag */
  173.     apr_text_header following_cdata;
  174.  
  175.     /** parent element */
  176.     struct apr_xml_elem *parent;    
  177.     /** next (sibling) element */
  178.     struct apr_xml_elem *next;    
  179.     /** first child element */
  180.     struct apr_xml_elem *first_child;
  181.     /** first attribute */
  182.     struct apr_xml_attr *attr;        
  183.  
  184.     /* used only during parsing */
  185.     /** last child element */
  186.     struct apr_xml_elem *last_child;
  187.     /** namespaces scoped by this elem */
  188.     struct apr_xml_ns_scope *ns_scope;
  189.  
  190.     /* used by modules during request processing */
  191.     /** Place for modules to store private data */
  192.     void *priv;
  193. };
  194.  
  195. /** Is this XML element empty? */
  196. #define APR_XML_ELEM_IS_EMPTY(e) ((e)->first_child == NULL && \
  197.                                   (e)->first_cdata.first == NULL)
  198.  
  199. /** apr_xml_doc: holds a parsed XML document */
  200. struct apr_xml_doc {
  201.     /** root element */
  202.     apr_xml_elem *root;    
  203.     /** array of namespaces used */
  204.     apr_array_header_t *namespaces;
  205. };
  206.  
  207. /** Opaque XML parser structure */
  208. typedef struct apr_xml_parser apr_xml_parser;
  209.  
  210. /**
  211.  * Create an XML parser
  212.  * @param pool The pool for allocating the parser and the parse results.
  213.  * @return The new parser.
  214.  */
  215. APU_DECLARE(apr_xml_parser *) apr_xml_parser_create(apr_pool_t *pool);
  216.  
  217. /**
  218.  * Parse a File, producing a xml_doc
  219.  * @param p      The pool for allocating the parse results.
  220.  * @param parser A pointer to *parser (needed so calling function can get
  221.  *               errors), will be set to NULL on successfull completion.
  222.  * @param ppdoc  A pointer to *apr_xml_doc (which has the parsed results in it)
  223.  * @param xmlfd  A file to read from.
  224.  * @param buffer_length Buffer length which would be suitable 
  225.  * @return Any errors found during parsing.
  226.  */
  227. APU_DECLARE(apr_status_t) apr_xml_parse_file(apr_pool_t *p,
  228.                                              apr_xml_parser **parser,
  229.                                              apr_xml_doc **ppdoc,
  230.                                              apr_file_t *xmlfd,
  231.                                              apr_size_t buffer_length);
  232.  
  233.  
  234. /**
  235.  * Feed input into the parser
  236.  * @param parser The XML parser for parsing this data.
  237.  * @param data The data to parse.
  238.  * @param len The length of the data.
  239.  * @return Any errors found during parsing.
  240.  * @remark Use apr_xml_parser_geterror() to get more error information.
  241.  */
  242. APU_DECLARE(apr_status_t) apr_xml_parser_feed(apr_xml_parser *parser,
  243.                                               const char *data,
  244.                                               apr_size_t len);
  245.  
  246. /**
  247.  * Terminate the parsing and return the result
  248.  * @param parser The XML parser for parsing this data.
  249.  * @param pdoc The resulting parse information. May be NULL to simply
  250.  *             terminate the parsing without fetching the info.
  251.  * @return Any errors found during the final stage of parsing.
  252.  * @remark Use apr_xml_parser_geterror() to get more error information.
  253.  */
  254. APU_DECLARE(apr_status_t) apr_xml_parser_done(apr_xml_parser *parser,
  255.                                               apr_xml_doc **pdoc);
  256.  
  257. /**
  258.  * Fetch additional error information from the parser.
  259.  * @param parser The XML parser to query for errors.
  260.  * @param errbuf A buffer for storing error text.
  261.  * @param errbufsize The length of the error text buffer.
  262.  * @return The error buffer
  263.  */
  264. APU_DECLARE(char *) apr_xml_parser_geterror(apr_xml_parser *parser,
  265.                                             char *errbuf,
  266.                                             apr_size_t errbufsize);
  267.  
  268.  
  269. /**
  270.  * Converts an XML element tree to flat text 
  271.  * @param p The pool to allocate out of
  272.  * @param elem The XML element to convert
  273.  * @param style How to covert the XML.  One of:
  274.  * <PRE>
  275.  *     APR_XML_X2T_FULL                start tag, contents, end tag 
  276.  *     APR_XML_X2T_INNER               contents only 
  277.  *     APR_XML_X2T_LANG_INNER          xml:lang + inner contents 
  278.  *     APR_XML_X2T_FULL_NS_LANG        FULL + ns defns + xml:lang 
  279.  * </PRE>
  280.  * @param namespaces The namespace of the current XML element
  281.  * @param ns_map Namespace mapping
  282.  * @param pbuf Buffer to put the converted text into
  283.  * @param psize Size of the converted text
  284.  */
  285. APU_DECLARE(void) apr_xml_to_text(apr_pool_t *p, const apr_xml_elem *elem,
  286.                                   int style, apr_array_header_t *namespaces,
  287.                                   int *ns_map, const char **pbuf,
  288.                                   apr_size_t *psize);
  289.  
  290. /* style argument values: */
  291. #define APR_XML_X2T_FULL         0    /**< start tag, contents, end tag */
  292. #define APR_XML_X2T_INNER        1    /**< contents only */
  293. #define APR_XML_X2T_LANG_INNER   2    /**< xml:lang + inner contents */
  294. #define APR_XML_X2T_FULL_NS_LANG 3    /**< FULL + ns defns + xml:lang */
  295.  
  296. /**
  297.  * empty XML element
  298.  * @param p The pool to allocate out of
  299.  * @param elem The XML element to empty
  300.  * @return the string that was stored in the XML element
  301.  */
  302. APU_DECLARE(const char *) apr_xml_empty_elem(apr_pool_t *p,
  303.                                              const apr_xml_elem *elem);
  304.  
  305. /**
  306.  * quote an XML string
  307.  * Replace '<', '>', and '&' with '<', '>', and '&'.
  308.  * @param p The pool to allocate out of
  309.  * @param s The string to quote
  310.  * @param quotes If quotes is true, then replace '"' with '"'.
  311.  * @return The quoted string
  312.  * @note If the string does not contain special characters, it is not
  313.  * duplicated into the pool and the original string is returned.
  314.  */
  315. APU_DECLARE(const char *) apr_xml_quote_string(apr_pool_t *p, const char *s,
  316.                                                int quotes);
  317.  
  318. /**
  319.  * Quote an XML element
  320.  * @param p The pool to allocate out of
  321.  * @param elem The element to quote
  322.  */
  323. APU_DECLARE(void) apr_xml_quote_elem(apr_pool_t *p, apr_xml_elem *elem);
  324.  
  325. /* manage an array of unique URIs: apr_xml_insert_uri() and APR_XML_URI_ITEM() */
  326.  
  327. /**
  328.  * return the URI's (existing) index, or insert it and return a new index 
  329.  * @param uri_array array to insert into
  330.  * @param uri The uri to insert
  331.  * @return int The uri's index
  332.  */
  333. APU_DECLARE(int) apr_xml_insert_uri(apr_array_header_t *uri_array,
  334.                                     const char *uri);
  335.  
  336. /** Get the URI item for this XML element */
  337. #define APR_XML_GET_URI_ITEM(ary, i) (((const char * const *)(ary)->elts)[i])
  338.  
  339. #if APR_CHARSET_EBCDIC
  340. /**
  341.  * Convert parsed tree in EBCDIC 
  342.  * @param p The pool to allocate out of
  343.  * @param pdoc The apr_xml_doc to convert.
  344.  * @param xlate The translation handle to use.
  345.  * @return Any errors found during conversion.
  346.  */
  347. APU_DECLARE(apr_status_t) apr_xml_parser_convert_doc(apr_pool_t *p,
  348.                                                      apr_xml_doc *pdoc,
  349.                                                      apr_xlate_t *convset);
  350. #endif
  351.  
  352. #ifdef __cplusplus
  353. }
  354. #endif
  355. /** @} */
  356. #endif /* APR_XML_H */
  357.